Liferay User Experience Customization

Table of Contents

 Introduction

 Themes

 Making your own theme

 Configuration

 Templates

 CMS + Portal = Website

 Conclusion
Introduction
Liferay has recently released version 3.5 of Liferay Portal. One major benefit of the new

release is that new features and key enhancements make it possible for you to seamlessly

integrate your website and portal, either by giving your portal the same look and feel as

your main website, or by rebuilding your website within Liferay Portal.

In this tutorial, we will explain Liferay Portal 3.5’s new "Themes” feature in detail. Then we

will discuss how to use Themes in conjunction with other new features to easily build your

website within Liferay Portal.

Themes
Themes make it possible to easily switch among different presentational or "look and feel"

layers. Within a single .war file, a designer/developer can deliver an integrated package of

JSP (or Velocity), Javascript, image and configuration files that will control all presentation

logic and design attributes for a portal community. Liferay Portal 3.5 comes with a handful

of pre-made themes that showcase the versatility and creative possibilities themes enable:

Figure 2.1: "Classic" Theme

Figure 2.2: "Breeze" Theme
 Figure 2.3: "Velocity" Theme Figure 2.4: "Genesis" Theme

Figure 2.5: "Clean" Theme Figure 2.6: "Brochure" Theme

Themes in Liferay Portal 3.5 are also incredibly flexible in how they can be applied:

 Different themes can be assigned to specific user groups (a.k.a. communities).

 Users can choose a unique theme for their own personal portal page

 Both Java Server Page (JSP) and Velocity (VM) languages are supported

 Themes are hot-deployable as .wars (when supported by the app server)

To select a different theme, simply go to the Look and Feel section (in the header bar) and

choose one of the available themes and a corresponding color scheme. The process is as

straightforward as setting a new desktop background in Windows.

Making Your Own Theme

Now that we’ve seen the power and flexibility of themes, let’s see how you can put your

creativity to work and design your own. Making a new theme requires only four main

steps:

1. Configure properties
2. Edit templates (JSP or VM)
3. Define CSS styles
4. Code JavaScript (optional)

Let’s take a high-level look at how Liferay created the JSP-based "Brochure" theme (Figure

2.6) by modifying a few things in a copy of the "Classic" theme (Figure 2.1).
Note: If you want to see an example using VM, take a look at the bundled "Velocity" theme

(Figure 2.3).

Configuration
To start, we created a copy of the "Classic" theme’s directory and renamed it "brochure."

(Figure 2.1.1.1). We then deleted the color-schemes directory because we decided we

would only have one color scheme for the "Brochure" theme. Although you don’t have to

follow the layout shown here, this convention will make your themes easier to organize

and keep them standard.

Figure 2.1.1.1 Directory structure

Once we have a directory to house our new theme, we need to let Liferay know the new
theme’s directory location. This is done in liferay-look-and-feel.xml (Figure

2.1.1.2). Notice that the theme configuration shows theme id="brochure" and identifies

the compatible version. The root-path, templates-path and images-path are also set here.

Make sure that these values match your directory structure.

<look-and-feel>
<compatibility>
<version>3.5.0</version>
</compatibility>
<theme id="brochure" name="Brochure">
<root-path>/html/themes/brochure</root-path>
<templates-path>/html/themes/brochure/templates</templates-path>
<images-path>/html/themes/brochure/images</images-path>
<template-extension>jsp</template-extension>
<color-scheme id="01" name="Default">
<!-- color-scheme content omitted to simplify example -->
</color-scheme>
</theme>
</look-and-feel>
Figure 2.1.1.2 liferay-look-and-feel.xml

Templates
Now that Liferay Portal is configured to load your theme, the next step is to edit the

template files that give the theme its uniqueness. Here’s a brief description of some of the

templates that are used in the default themes:

init.jsp Initializes variables and properties needed for the theme.

css.jsp Contains CSS style definitions for your entire theme.

portal_normal.jsp Controls the layout of portal templates for normal pages.

portal_pop_up.jsp Controls the layout of portal templates for pop-ups.

top.jsp Draws the top of the portal.

bottom.jsp Draws the bottom of the portal.

navigation.jsp Draws the navigation bar of the portal.

portlet_top.jsp Draws the top of each portlet.

portlet_bottom.jsp Draws the bottom of each portlet.

javascript.jsp Contains JavaScript declarations.

Each template controls the layout of a particular area within the portal. For instance,
portlet_top.jsp controls the top portion of each portlet; navigation.jsp determines
how the navigation bar will look.

Keep in mind that not all of these templates require modification; nor are you limited to

the ones mentioned here. Feel free to add another template to control a different area of
the portal. Just make sure to include the template in portal_normal.jsp and/or

portal_pop_up.jsp.

A number of changes were made to these templates for the brochure theme. Highlighted,

you can see one such major change made to the placement and appearance of the portal

configuration menu (Figures 2.1.2.1 and 2.1.2.1):

Figure 2.1.2.1 The "Classic" theme's portal config menu is integrated with the

tabs.
Figure 2.1.2.2 The "Brochure" theme's portal config menu is relocated to the top

of the portal.

In the "Classic" theme, the portal configuration menu is part of the navigation bar. It

consists of buttons and a dropdown menu. By contrast, the "Brochure" theme has the

portal configuration menu relocated to the top of the portal and separated from the

navigation bar. Also notice that the buttons are now simple text links. Some of the code

changes required highlighted below in Figure 2.1.2.3:

<div id="layout-outer-side-decoration">
<div id="layout-inner-side-decoration">
<div id="layout-top-decoration">
<div id="layout-corner-ul"></div>
<div id="layout-corner-ur"></div>
</div>
<div id="layout-box">
<div id="layout-top">
<div id="layout-logo">
<a class="bg" href="<%= themeDisplay.getPathFriendlyURL()
%>/guest/home"><img border="0" hspace="0" src="<%=
themeDisplay.getCompanyLogo() %>" vspace="0"></a>
</div>

<c:if test="<%= themeDisplay.isSignedIn() %>">

<div id="layout-user-menu">
<a style="font-size: 8pt;" href="<%= themeDisplay.getURLSignOut()
%>"><bean:message key="sign-out" /></a> -

<c:if test="<%=
GetterUtil.getBoolean(PropsUtil.get(PropsUtil.UNIVERSAL_PERSONALIZATI
ON)) || RoleLocalServiceUtil.isPowerUser(user.getUserId()) %>">
<a style="font-size: 8pt" href="<%= themeDisplay.getPathMain()
%>/portal/personalize_forward?group_id=<%= portletGroupId %>"><%=
LanguageUtil.get(pageContext, "content-and-layout") %></a> -
</c:if>

<c:if test="<%=
GetterUtil.getBoolean(PropsUtil.get(PropsUtil.LOOK_AND_FEEL_MODIFIABL
E)) %>">
<a style="font-size: 8pt" href="<%= themeDisplay.getPathMain()
%>/portal/look_and_feel_forward?group_id=<%= portletGroupId %>"><%=
LanguageUtil.get(pageContext, "look-and-feel") %></a> -
</c:if>

<font class="portlet-font" style="font-size: 8pt;">

<%= LanguageUtil.get(pageContext, "my-communities") %>
</font>

<% String selectedStyle = "style=\"background: " +

colorScheme.getPortletMenuBg() + "; color: " +
colorScheme.getPortletMenuText() + ";\" "; %>

<font size="2">
<select name="my_communities_sel" style="font-family: Verdana, Arial;
font-size: smaller; font-weight: normal;" onChange="self.location =
'<%= themeDisplay.getPathMain() %>/portal/group_forward?group_id=' +
this.value;">
<option <%= !layout.isGroup() ? selectedStyle : "" %> value="<%=
Group.DEFAULT_PARENT_GROUP_ID %>"><%= LanguageUtil.get(pageContext,
"desktop") %></option>

<% List myCommunities =

UserLocalServiceUtil.getGroups(user.getUserId());
for (int i = 0; i < myCommunities.size(); i++) {
Group myCommunity = (Group)myCommunities.get(i);
%>
<option <%= layout.isGroup() &&
layout.getGroupId().equals(myCommunity.getGroupId()) ? selectedStyle
+ "selected" : "" %> value="<%= myCommunity.getGroupId() %>"><%=
myCommunity.getName() %></option>

<% } %>

</select>
</font>
</div>
</c:if>
Figure 2.1.2.3 top.jsp for the "Brochure" theme

CSS Styles
Another major part of every theme is the collection of presentation attributes such as font

size, background color, padding and margin. The best way to control these attribute in
your theme is to use cascading style sheets (CSS). As mentioned briefly above, css.jsp

contains all the CSS style definitions for your theme. Liferay Portal’s default themes include

all JSR-168 standard style definitions. You may also add theme-specific style definitions to

css.jsp. Using the templates and adding custom images as necessary, you can use

standard and custom style definitions to give your theme a distinctive look and feel. Let’s

look at some of the style changes made in the "Brochure" theme.

Header Bar
.portlet-header-bar {
background-color: #e0e0e0;
margin: 0 1px 0 1px;
padding: 3px 0px 3px 0px;
position: relative;
z-index: 2;
}

<%@ include file="init.jsp" %>

<div class="portlet-container" style="width: <%=

portletDisplay.getWidth() %>">
<div class="portlet-header-bar">
<c:if test="<%= Validator.isNotNull(portletDisplay.getTitle())
%>">
<div class="portlet-title">
<b> <%= portletDisplay.getTitle() %> </b>
</div>
</c:if>
The style definition portlet-header-bar is used in the portlet_top template. The

portlet_top template is used to draw the top of each portlet within the portal. As you
can see from the portlet-header-bar definition, the header bar for each portlet should

have a gray background color, with a small margin on its sides, padding on top and

bottom, positioned relatively and with a z-index of 2.

Dynamic Style Values

Another flexibility aspect to highlight is that style values can be retrieved dynamically from
color scheme variables defined in liferay-look-and-feel.xml. Because the style

sheet is a JSP file, you can use JSP tags to dynamically assign some of your style definition

values. For example:

.portlet-title {
color: <%= colorScheme.getPortletTitleText() %>
font-family: Tahoma, Arial;
font-size: smaller;
vertical-align: middle;
}
In the above code, portlet-title’s color attribute has its value retrieved dynamically.

This way, depending on the color scheme selected on the "Look and Feel" page in the

portal, the title bar will have a color appropriate to the currently selected color scheme.
Please refer to the theme user guide for more information.

JavaScript
Lastly, you are free to use JavaScript to create a more dynamic interface for your theme.

To use a script, all you have to do is put the script file inside your theme directory, then
provide the location of this file in the script declaration in javascript.jsp. For example,

if your JavaScript file is called my_script.js and it’s located in

html/themes/my_themes/js, make the following declaration in javascript.jsp:

<script language="JavaScript" src="<%=

themeDisplay.getPathThemeRoot() %>/js/my_script.js"></script>
The JSP expression <%= themeDisplay.getPathThemeRoot() %> helps keep you from

hard-coding information in your templates. Refer to the API to see other variables and

methods available to you.

Both the "Clean" theme (Figure 2.5) and the "Genesis" theme (Figure 2.4) use JavaScript
to create a dynamic interface.

CMS + Portal = Website

In addition to themes, Liferay Portal 3.5 has several enhancements that make it very

straightforward to combine static CMS articles and functionality-rich portlets on the same

portal page. One direct application of this capability would be to create your public website

using Liferay, and thereby enable the inclusion of portlets on your website. Not only would

you be able to reuse functional components and find innovative ways to use them, but you

could also quickly build new pages out of common components within a tightly-managed

CMS framework.

As an example, suppose an insurance company wants to show their customers how much

they can save by switching to their insurance plan. Online visitors can go to their website,

fill out a short form, and receive pricing information instantaneously. If this insurance

company uses Liferay 3.5 to build their website, they can easily develop a pricing

calculator portlet, grant guest access, and display it on the front page of their website. The

CMS-managed article describing the plan can be placed right beside the calculator portlet.

Also, incorporating portlets into your website helps to encourage reuse. If two different

pages on your website need to offer the same functionality, one portlet can simply be

placed in both pages.

Liferay Portal 3.5 also comes with portlets specifically designed to help you build a public

website easily. The Breadcrumb Portlet keeps track of how deep a user has gone into the

navigation of a site. The Navigation Portlet can be configured to act as a standard nested
navigation menu. These and other portlets can be re-used and easily included on every

content page where they are needed, and once the main Theme layout has been created,

psges can be put together using these portlets without touching the presentation code.

Layout is handled strictly through portal page configuration.

Besides providing functionality, a website also needs to provide information. Liferay Portal

3.5 allows CMS articles to be inserted into your portal just like any other portlet. You can

thus easily bring various articles together to assemble a website.

Taking the above example, the insurance company may want one portlet containing a CMS

article describing their pricing. Right next to it is another portlet with a CMS articles haring

customer testimonials. The layout of the page the articles live in is managed within the

portal’s admin section, and the content and layout of the individual articles is easily

maintained through the journal portlet.

Liferay Portal 3.5 also ships with the Runtime Portlet and the Portlet Aggregator. The

Runtime Portlet is used to embed portlets into CMS articles. This portlet is used at

Liferay.com to embed an instance of the Login Portlet within the article that’s displayed on

the main web page.

The Portlet Aggregator provides a flexible means to lay out several portlets. You are no

longer confined to the strict rigidity of a column layout, but can rather set the layout of

several portlets dynamically using HTML and CSS.

In Liferay’s next Javalobby article, we’ll explore both of these portlets in greater detail.

Note: For documentation on Liferay’s CMS, please see the CMS User Guide.

Example of CMS and Web Portal Integration

Liferay’s main website was recently rebuilt to utilize the portal instead of using linked CMS

pages (which showcased version 3.2 capabilities). In this new paradigm, each page on the

website is a layout (page) comprised of several different portlets. To illustrate, let’s take

Liferay’s "Company Overview" page as an example. Figure 2.1.4.1 shows the webpage

with each of the five portlets marked. (You can view the actual page here.)
Figure 2.1.4.1 Company Overview

Company Overview, like most other pages on Liferay.com, is a portal layout (page) with

two columns, one narrow and one wide, containing various portlets that supply its content.

Portlets two and four, denoted in Figure 2.1.4.1, are instances of the Navigation and

Breadcrumb Portlets, respectively. The remaining three portlets are instances of the

Journal Content portlet; each contains its own CMS article. Portlet one and three contain a

single picture each, and portlet five contains a detailed overview of Liferay.

You can add, delete, and organize page layouts by using the Admin section (Figure

2.1.4.2), accessed by the "Content and Layout" button.

Figure 2.1.4.2 Admin Portlet

For the Company page, we added the "Company" layout right under the "Home" layout.

Also notice the Friendly URL field. This field allows you to assign a simple URL to a layout.

So instead of linking to this page with the URL

www.liferay.com/c/portal/layout?p_p_id=34..., you can use a simplified URL like

www.liferay.com/web/guest/company.

Once the "Company" page layout has been added, you can add different portlets to it to

quickly assemble your webpage.

For example, to add the Breadcrumb Portlet to the right column:

1. Go to the bottom of the right column.

2. Choose "Breadcrumb" in the dropdown menu.
3. Click the "Add" button.

To add a CMS article in the left column:

1. Go to the bottom of the left column.

2. Choose "Journal Content" in the dropdown menu.
3. Click the "Add" button.
4. Click the "Edit" button to specify the ID of the article you want.
5. Specify whether you would like to see a border.
6. Add an optional title and click the "Save Settings" button.

Note: When assembling your webpage, remember to extract all the presentation attributes

to your theme. This way, all the attributes are centralized. For example, to remove the gap

between the wide and narrow columns, we set the "margin" attribute in the "Brochure"

theme to zero.
Conclusion
Liferay 3.5 provides a lot of flexibility and control to customize the overall user experience

of your portal or website. The availability of a number of different ways to manage, use

and display CMS content and portlets begets limitless possibilities for innovation using

Liferay Portal.

To see Liferay Portal 3.5 in action, visit demo.liferay.net and create a user account for

yourself. You can also explore Liferay.com to get a sense of how the portal was used to

build that site and begin to imagine the possibilities for your own website or portal.

Discuss this article with Wilson Man

Download the PDF version of this article!